fix(captions): place captions by anchor and margin, not by an invisible band (rc.3) - #484

…le band

Replaces the whole placement model. Every control now names the edge it measures
from, and there is exactly one per axis:

  anchorV + insetY   bottom | top, and a distance from that edge
  anchorH + insetX   left | center | right, and a distance from that edge

Deleted: verticalPosition, offsetY, offsetX, width, textAlign — and the
machinery that existed only to compensate for the old geometry (the fixed 22%
band, the ink-height estimate, the overhang, the reachable-offset range, the
preset-vs-slider epsilon).

The old model drew every caption inside an invisible fixed-height box and let
each rasterizer centre the ink in it, while the only thing on screen — the
background plate — hugs the text. So `width` changed nothing visible until the
text happened to wrap; the horizontal offset moved a band the text floated
inside; text-align fought that offset for the same outcome; wrapping grew a
centred block from both edges, which moved the caption vertically when nothing
vertical had been touched; and the vertical offset had to be signed and clamped
against an estimate, which is where "-7.3%" came from. All five are the same
decision, so this replaces the decision rather than the controls.

`width` becomes a derived column instead of a control (BBC's line-length table:
68% landscape, 90% vertical). How much text is on screen is already a legible
question elsewhere — min/max words per line. The default inset follows the
output aspect, because 5% on a 9:16 export is under the platform's own chrome.

Migration reproduces the PIXELS, not the fields: the old band's geometry is
known, so the drawn block's edges are recoverable, and the nearer one becomes
the anchor. A migrated project does not move on screen. Line breaks do change
for a project with a non-default width, since that WAS the wrap column.

Tests assert the invariant as a property — the anchored edge lands at 100−insetY
(or insetY) for every font size, background state and inset — rather than
pinning numbers a future change would just have to update.

(cherry picked from commit b4810d1)

The Linux anchor test measured the bottom-most inked row and called a 184→199
move a drift. It is not: "Hx" has no descenders and "replier" does, so the ink
reaches further down inside an identically-placed line box. What this code pins
is the line box — and therefore the plate, which is what the compositor draws
and what the viewer sees. Anchoring the box rather than the last glyph pixel is
the behaviour every text renderer has.

So the assertion moves to `atlas.plate`, which is deterministic and is the
actual contract. The ink is still checked, but only for the thing that is true
of it: that it stays inside the plate carrying it, with the same `pad_y`
tolerance `the_plate_hugs_the_text_instead_of_filling_the_box` already uses for
that relationship — a glyph may overshoot its own line box slightly, which is
precisely the assumption the first version got wrong.

Found by CI: only text_windows.rs compiles on the machine this was written on.

(cherry picked from commit b061746)

…igrate insetX

Two findings from CodeRabbit's review of #482, both real.

**The plate lost its margin on the anchored side.** Pinning the TEXT block flush
against the box edge left the plate laying all of its padding on the opposite
side and none on the anchored one: at the default bottom anchor the background
hugged the glyphs' baseline exactly while breathing twice as much above them.
What should touch the box edge is the plate — that is what the viewer sees, and
what the anchor invariant is stated in terms of. Reserving `pad_y` on the
anchored side puts the plate's edge in the same place and makes its padding
symmetric again.

Conditioned on a plate actually being drawn, on all three backends. Windows was
already inset but did it unconditionally, which would have placed its glyphs
`pad_y` away from Linux and macOS whenever the background was off; it is now
conditional too, so the three agree in both states.

**The migration snapped left/right captions to the frame edge.** It returned
`insetX: 0` for every document, so a migrated caption whose band sat at 5% moved
to 0%. The vertical half already reconstructed the drawn edge exactly; the
horizontal half now does the same from the values it had already computed —
which is what "reproduce the pixels, not the fields" was supposed to mean.

(cherry picked from commit 18f4d09)

rustc rejects `///` on a parameter; it has to be a plain `//`. Only
text_macos.rs compiles on macOS, so the machine this was written on could not
see it — and rustfmt parses the file happily, so a local syntax gate would not
have caught it either. CI did.

(cherry picked from commit 2cf1b22)

`patchCaptionSettings` read the document without an aspect, so the write that
MATERIALISES the defaults into a project that never had caption settings always
wrote the landscape ones. A 9:16 export got `insetY: 5` frozen in, and the
stored value then won for good — putting the caption under the platform's own
chrome, which is the exact failure the aspect-derived default exists to prevent.

`useCaptions` now resolves the aspect once (through `resolveAspectRatioValue`,
the same resolver the preview and the scene description use, so all three agree
on what a legacy "native" selection means) and hands it to the read and to every
write: `set`, `setLive` and the language reset in `deleteTranslation`.

Found by CodeRabbit on #482.

(cherry picked from commit 096a551)

The anchor redesign's doc rewrite rode along with the guide-overlay commit,
which is add-then-revert within the PR and was therefore skipped here. This
carries the surviving half: the settings table, and the sections that described
the fixed band, the overhang and the preset machinery — none of which exists any
more.

Applied as one commit rather than cherry-picked because this branch's copy of the
file never received #471's docs commit (docs are excluded from the cherry-pick
lane), so its lineage differs from main's and the patch does not apply.

… padding

1.5% from the anchored edge, 10% from the horizontal one. Picked by eye against
the editor's default padding rather than from a broadcast spec: the footage sits
inset inside the frame, so what reads as "just off the edge" is a much smaller
number than the 5% BBC states for a full-bleed broadcast frame.

Landscape only — those two values were eyeballed on a 16:9 export. Vertical
keeps its 12.5%, which answers a different question: TikTok, Reels and Shorts
draw their own chrome over the bottom eighth of a 9:16 video, so 1.5% there
would put the caption behind a UI. Nobody has looked at that case, so it stays
on the conservative value.

(cherry picked from commit 7dcd9f0)